<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>phpManta - Mdoc - Technical reference</title>
</head>

<body>
<h1>Mdoc technical reference</h1>
<p>This page provides author notes used to design the Mdoc class processings.</p>
<h2>Basics</h2>
<p>Variables in PHP are represented by a dollar sign followed by the name of
  the variable. The variable name is case-sensitive.</p>
<p>  Variable names follow the same rules as other labels in PHP. A valid variable
  name starts with a letter or underscore, followed by any number of letters,
  numbers, or underscores. As a regular expression, it would be expressed thus:
  '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*' </p>
<p> For our purposes here, a letter is a-z, A-Z, and the ASCII characters from
127 through 255 (0x7f-0xff).</p>
<p>A <em>documenting</em> comment starts with /** followed by a blank character (the Perl \s char, usualy space or new line). </p>
<p>The documention parsing starts as of the first <em>documenting</em> comment, except for the CVS keyword parsing, thus some undocumented code can preceeds the constant, library or class declaration . </p>
<h2>Constraints and recommendations</h2>
<p>While PHP allows a lot of various comment styles, the Mdoc parser doesn't
  support too weird and ugly comment styles. This  limitation provides constraints
  which help in commenting code nicely.</p>
<h3>Characters /** in comments</h3>
<p>The sequence /** must be quoted in code comments to avoid the parser to split the code fragment within a comment. </p>
<pre>&lt;?

// Don't do this:

// Starting "/**" is NOT part of fragments at this stage, so remove "/* ... */"
$source_frags[$index] = preg_replace('!/\*.*\*/!s', "", $fragment);

// but do this

Starting <strong>"/**"</strong> is NOT part of fragments at this stage, so remove "/* ... */"
$source_frags[$index] = preg_replace('!/\*.*\*/!s', "", $fragment);
?&gt;</pre>
<h3>Usage of @ char in descriptions</h3>
<p>If you start a line with @ in the long description, the parser will consider it as the fist @info keyword, which isn't wht you expect. </p>
<pre>&lt;?

// Don't do this:

/**
 * Syntactically correct PHP5 class example.

 *
 * For PHP interpreter, the default scope is "public" (so @private and 
 * <strong>@protected</strong> should not be forgotten).
 */

// but do this

/**
 * Syntactically correct PHP5 class example.

 *
 * For PHP interpreter, the default scope is "public" (so @private  
 * and <strong>@protected</strong> should not be forgotten).
 */
?&gt;</pre>
<h3>Commenting in constant declarations</h3>
<p>Commenting in between the <em><strong>const</strong></em> keyword and the
  constant identifier is not allowed, as well as <em><strong>var</strong></em> keyword and property identifier
  (PHP4) :</p>
<pre>&lt;?php
 
/* These styles are not allowed (and somehow ugly) */ 

const  // An in-class constant definition comment
  START = 0;  
  
const 
  // An in-class constant definition comment
  START = 0;
  
<strong>/* Recommendation (the 1st is prefered)*/  

const START = 0;  // An in-class constant definition comment</strong>

/* Same scheme for PHP4 properties */

var  // A property definition comment
  $myprop = 0;  

<strong>/* Recommendation */  

var $myprop = 0;  // A property definition comment</strong>

?&gt;</pre>
<p>Commenting in between the <em><strong>define</strong></em> keyword and the constant identifier is not
allowed:</p>
<pre>&lt;?php 

/* This style is not allowed (while is weird but is correct PHP syntax) */ 

define(  
         // Real code comment to ignore
         &quot;CLAS_INTERNAL_FOUR&quot;, 
         4);

<strong>/* Recommendation, the 2nd might be prefered */

         // Real code comment to ignore  
define(  &quot;CLAS_INTERNAL_FOUR&quot;, 
         4);

// Real code comment to ignore  
define(&quot;CLAS_INTERNAL_FOUR&quot;, 
       4);</strong>

?&gt;</pre>
<p>For constant declaration in <em><strong>group</strong></em>, the subcomment must be one line and you'd keep the block somehow simple to ensure a correct parsing by Mdoc parser. If the block is too complex, with many subcomments, it's recommended to declare the constant individually. Here is a good example of constant block declaration:</p>
<pre>&lt;?php 

/**
 * New line chars.
 *
 * This is the long description for the whole block, so it applies
 * to every constant.
 */
const NL_DOS = "\r\n";  // for Windows environment
const NL_MAC = "\r";    // for Mac environment
const NL_NIX = "\n";    // for Unix/Linux environment

/**
 * New line chars.
 *
 * Use # inline comment to exclude these sbucomment from the source
 * code documentation.
 */
const NL_DOS = "\r\n";  # inline comment ignored for documenting
const NL_MAC = "\r";
const NL_NIX = "\n";

?&gt;</pre>
<h2>Comment elements not allowed</h2>
<p>For obvious consistency reasons (and internal represention choices), some comment info keys aren't allowed,</p>
<blockquote>
  <p>not allowed in any comment:</p>
  <blockquote>
    <p>      @short_description<br />
      @long_description
        <br />
        @cvs</p>
  </blockquote>
  <p>not allowed in <em>library</em> comment:</p>
  <blockquote>
    <p>@name<br />
    @comment </p>
  </blockquote>
  <p>not  allowed in <em>class</em> comment:</p>
  <blockquote>
    <p>@name<br />
      @declaration<br />
      @comment <br />
      @line<br />
      @extends (PHP5)<br />
      @implements (PHP5)
      <br />
    @final (PHP5)<br />
    @abstract (PHP5)<br />
    @interface (PHP5)</p>
  </blockquote>
<p>not allowed in <em>method</em> and <em>function</em> comment:</p>
  <blockquote>
    <p>      @code<br />
      @comment <br />
@line<br />
@final (PHP5)
<br />
@public (PHP5) <br />
@private (PHP5) <br />
@protected (PHP5)    </p>
  </blockquote>
<p>not allowed in <em>property</em> comment:</p>
  <blockquote>
    <p> @code<br />
      @comment <br />
@line      <br />
      @initial<br />
      @static (PHP5) <br />
      @public (PHP5) <br />
@private (PHP5) <br />
@protected (PHP5) </p>
  </blockquote>
</blockquote>
<p> In<em> constant</em> and <em>constant group</em> comment, the only comment info keys allowed are:</p>
<blockquote>
  <p> @experimental<br />
    @type<br />
    @warning</p>
</blockquote>
<p>When the Mdoc parser encounters such a comment element, a parsing error is  issued at  warning level. </p>
<h2>Support of CVS keywords comments </h2>
<p> Mdoc class supports the CVS keywords declared is anu block or full-line comments:</p>
<!-- every $ is spanned as <span>$</span> to avoid CVS substitutions in this paragraph -->
<blockquote>
  <p><span>$</span>Author: ...<span>$</span> <br />
<span>$</span>CVSHeader: ...<span>$</span> <br />
<span>$</span>Date: ...<span>$</span><br />
<span>$</span>Header: ...<span>$</span><br />
<span>$</span>Id: ...<span>$</span><br />
<span>$</span>Name: ...<span>$</span><br />
<span>$</span>Locker: ...<span>$</span><br />
<span>$</span>Log: ...<span>$</span><br />
Revision 1.5 2005/10/07 13:44:48 joe <br />
CVS commit message entered by Joe to describe this revision </p>
  <p> Revision 1.4 2005/10/07 13:43:27 fred <br />
  CVS commit message entered by Fred to describe this revision <br />
  <br />
  <span>$</span>RCSfile: ...<span>$</span><br />
  <span>$</span>Revision: ...<span>$</span><br />
  <span>$</span>Source: ...<span>$</span><br />
  <span>$</span>State: ...<span>$</span></p>
</blockquote>
<p>If Mdoc finds other CVS keywords, they are ignored. If the same keyword is found several tmimes, only the first one is retainded, following ones are ignored, considering they are regular comments. </p>
<blockquote>
  <p> <span>$</span>Author<span>$</span> <br />
The login name of the who checked in the revision. </p>
  <p><span>$</span>CVSHeader<span>$</span> <br />
  A standard header (similar to <span>$</span>Header<span>$</span>, but with the CVS root stripped off). It contains the relative pathname of the RCS file to the CVS root, the revision number, the date (UTC), the author, the state, and the locker (if locked). Files will normally never be locked when you use CVS. </p>
  <p>Note that this keyword has only been recently introduced to CVS and may cause problems with existing installations if <span>$</span>CVSHeader<span>$</span> is already in the files for a different purpose. This keyword may be excluded using the KeywordExpand=eCVSHeader in the `CVSROOT/config' file.</p>
  <p> <span>$</span>Date<span>$</span> <br />
  The date and time (UTC) the revision was checked in. </p>
  <p> <span>$</span>Header<span>$</span> <br />
  A standard header containing the full pathname of the RCS file, <br />
  the revision number, the date (UTC), the author, the state, and <br />
  the locker (if locked). Files will normally never be locked when <br />
  you use CVSNT. </p>
  <p> <span>$</span>Id<span>$</span> <br />
  Same as <span>$</span>Header<span>$</span>, except that the RCS filename is without a path. </p>
  <p> <span>$</span>Name<span>$</span> <br />
  Tag name used to check out this file. The keyword is expanded only<br />
  if one checks out with an explicit tag name. For example, when <br />
  running the command cvs co -r first, the keyword expands to Name: <br />
  first. </p>
  <p> <span>$</span>Locker<span>$</span> <br />
  The login name of the who locked the revision (empty if not <br />
  locked, which is the normal case unless cvs admin -l is in use). </p>
  <p> <span>$</span>Log<span>$</span> <br />
  The log message supplied during commit, preceded by a header <br />
  containing the RCS filename, the revision number, the author, and <br />
  the date (UTC). Existing log messages are not replaced. Instead, <br />
  the new log message is inserted after <span>$</span>Log:...<span>$</span>. Each new line is <br />
  prefixed with the same string which precedes the <span>$</span>Log keyword. For <br />
  example, if the file contains </p>
  <pre>
    /* Here is what people have been up to:
    *
    * <span>$</span>Log: frob.c,v <span>$</span>
    * Revision 1.1 1997/01/03 14:23:51 joe
    * Add the superfrobnicate option
    *
    */</pre>
then additional lines which are added when expanding the <span>$</span>Log keyword <br />
    will be preceded by * . Unlike previous versions of CVSNT and RCS, the <br />
    comment leader from the RCS file is not used. The <span>$</span>Log keyword is useful<br />
    for accumulating a complete change log in a source file, but for several <br />
    reasons it can be problematic. See Log keyword.
  </p>
<p> <span>$</span>RCSfile<span>$</span> <br />
The name of the RCS file without a path. </p>
  <p> <span>$</span>Revision<span>$</span> <br />
  The revision number assigned to the revision. </p>
  <p> <span>$</span>Source<span>$</span> <br />
  The full pathname of the RCS file. </p>
  <p> <span>$</span>State<span>$</span> <br />
  The state assigned to the revision.</p>
</blockquote>
<h2>Bugs</h2>
<p>If Mdoc class fails to document  your code correctly, you may submit it by
  mail to jmfaure at users.sourceforge.net ; please ensure your code is parsed
  without error by PHP before sending it. </p>
<p>&nbsp;</p>
</body>
</html>
